package edu.umd.ion.wavemeter.service;

import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;

/**
 * Remote Service definition of the interface. The functions defined here have to be
 * implemented in class WavemeterServiceImpl on the server side.
 * The class WavemeterServiceAsync contains the asynchronous definition of these functions.
 * See server side class for a description of the functions.
 * @author monroe-lab
 *
 */
@RemoteServiceRelativePath("wavemeter-status")
public interface WavemeterService extends RemoteService 
{
	/**
	 * Polls the current data of the wavemeter.
	 * @param mask Datastructure defining what data is to be sent and when the last dataset
	 * the client already received was taken.
	 * @return New Measurement Data
	 * @throws WavemeterException
	 */
	WavemeterData pollWavemeter(WavemeterDataMask mask ) throws WavemeterException;
	/**
	 * Activate or deactivate a channel
	 * @param Channel index
	 * @param Active activate 
	 * @throws WavemeterException in case of error
	 */
	void setActive( int Channel, boolean Active) throws WavemeterException;
	/** Set Exposure mode of a channel
	 * @param channel index
	 * @param mode true for auto exposure false for fixed exposure
	 * @throws WavemeterException in case of error
	 */
	void setExposureMode(int channel, boolean mode) throws WavemeterException;
	/** Set exposure time
	 * @param Channel index
	 * @param array index (1 or 2)
	 * @param Value in ms
	 * @throws WavemeterException in case of error
	 */
	void setExposure(int Channel, int array, int Value) throws WavemeterException;
	/** Set averaging --- not implemented
	 * @param Channel index
	 * @param num number of averages
	 * @throws WavemeterException
	 */
	void setAverage(int Channel, int num) throws WavemeterException;
	/** Start or Stop the Wavemeter
	 * @param start 
	 * @throws WavemeterException
	 */
	void setMeasurement(boolean start) throws WavemeterException;
	/**Enable or Disable Wide mode
	 * @param wide
	 * @throws WavemeterException
	 */
	void setWideMode(boolean wide) throws WavemeterException;
	/** Enable/Disable Pulsed mode
	 * @param pulsed
	 * @throws WavemeterException
	 */
	void setPulseMode(boolean pulsed) throws WavemeterException;
	/** Enable/Disable Fast mode
	 * @param fast
	 * @throws WavemeterException
	 */
	void setFastMode(boolean fast) throws WavemeterException;
	/** Enable disable builtin regulation
	 * @param regulate
	 * @throws WavemeterException
	 */
	void setRegulationEnable(boolean regulate) throws WavemeterException;
	/** Enable/Disable switcher mode
	 * @param switcher
	 * @throws WavemeterException
	 */
	void setSwitcherMode(boolean switcher) throws WavemeterException;
	/** Shutdown the server process. This stops the server.
	 *  To restart the server stop and restart tomcat
	 */
	void shutdown();
	/** Clear the PID Integrator history
	 * @param channel index
	 * @throws WavemeterException
	 */
	void clearPIDHistory(int channel) throws WavemeterException;
	/** Set PID settings
	 * @param settings
	 * @return PIDSettings the used settings are echoed
	 * @throws WavemeterException
	 */
	PIDSettings setPID( PIDSettings settings ) throws WavemeterException;
	/** Get the PIDSettings
	 * @param Channel index
	 * @return PIDSettings
	 * @throws WavemeterException
	 */
	PIDSettings getPID( int Channel ) throws WavemeterException;
	/** Define which PIDSettings fields are actually relevant to the server.
	 * Used to make unused settings invisible on the client
	 * @return PIDSettingsInUse
	 * @throws WavemeterException
	 */
	PIDSettingsInUse getPIDSettingsInUse() throws WavemeterException;
	/** Set the PIDCourse
	 * @param Channel index
	 * @param Course 
	 * @return PIDCourse as interpreted by the server
	 * @throws WavemeterException
	 */
	String setPIDCourse( int Channel, String Course ) throws WavemeterException;
	/** Suggestions for PID Courses
	 * @param Channel
	 * @return String[] previously used settings
	 * @throws WavemeterException
	 */
	String[] getPIDCourseSuggestions( int Channel ) throws WavemeterException;
	/** Store the xml display settings
	 * @param username 
	 * @param settings xml document
	 * @throws WavemeterException
	 */
	void setSettings(String username, String settings) throws WavemeterException;
	/** Retrieve the xml display settings document
	 * @param username
	 * @return
	 * @throws WavemeterException
	 */
	String getSettings(String username) throws WavemeterException;
	/** Set the Interlock settings
	 * @param Interlock
	 * @throws WavemeterException
	 */
	void setInterlock(InterlockSettings Interlock) throws WavemeterException;
	/** Get the Interlock Settings
	 * @param Channel
	 * @return Interlock Settings as honored by the server
	 * @throws WavemeterException
	 */
	InterlockSettings getInterlock(int Channel) throws WavemeterException;
	/** Store Calibration settings --- does NOT calibrate the wavemeter
	 * @param Channel
	 * @param Settings
	 * @throws WavemeterException
	 */
	void setCalibrationSettings(int Channel, CalibrationSettings Settings) throws WavemeterException;
	/** Retrieve the Calibration settings
	 * @param Channel
	 * @return CalibrationSettings
	 * @throws WavemeterException
	 */
	CalibrationSettings getCalibrationSettings(int Channel) throws WavemeterException;
	/** Get all available usernames
	 * @return String[] usernames
	 * @throws WavemeterException
	 */
	String[] getUsernames() throws WavemeterException;
	/** Calibrate the wavemeter the supplied parameters
	 * @param unit not used, always give the number in nm
	 * @param value wavelength in nm
	 * @param channel index
	 * @return CalibrationResult
	 * @throws WavemeterException
	 */
	CalibrationResult calibrate( int unit, double value, int channel ) throws WavemeterException;
	/** Retrieve list of previous calibrations
	 * @return CalibrationResults
	 * @throws WavemeterException
	 */
	CalibrationResult[] calibrationHistory() throws WavemeterException;
	/** Retrieve Channel Routing information (just FYI)
	 * @return ChannelRoutingInfo
	 * @throws WavemeterException
	 */
	ChannelRoutingInfo[] channelRouting() throws WavemeterException;
	/** Retrieve basic information about this channel
	 * @return ChannelInfo
	 * @throws WavemeterException
	 */
	ChannelInfo[] channelInfo() throws WavemeterException;
	/** Add this name to the channel --- used for the list 
	 * @param Channel
	 * @param Name
	 * @throws WavemeterException
	 */
	void addChannelName(int Channel, String Name) throws WavemeterException;
	/** Set the exposure parameters (if allowed)
	 * @param ExposureParams
	 * @return the new Exposure Parameters
	 * @throws WavemeterException
	 */
	DynamicExposureParameters setExposureParameters(DynamicExposureParameters ExposureParams) throws WavemeterException;
	/** Get the currently active exposure Parameters
	 * @return Exposure Parameters
	 * @throws WavemeterException
	 */
	DynamicExposureParameters getExposureParameters() throws WavemeterException;
	/** Is this client running on the same machine as the server
	 * @return is local client
	 */
	Boolean isLocalClient();
	int getNumberOfChannels();
	int getNumberOfPIDChannels();
	
	void raiseChannelEvent(ChannelEvent E) throws WavemeterException;
}
